@formatjs/intl-relativetimeformat

What is @formatjs/intl-relativetimeformat?

@formatjs/intl-relativetimeformat is a JavaScript library that provides a way to format relative time strings, such as '3 days ago' or 'in 2 weeks', using the ECMAScript Internationalization API (Intl.RelativeTimeFormat). It is part of the FormatJS suite of libraries designed to help with internationalization in JavaScript applications.

What are @formatjs/intl-relativetimeformat's main functionalities?

Basic Relative Time Formatting

This feature allows you to format relative time strings in a human-readable format. The example shows how to create an instance of IntlRelativeTimeFormat and use it to format relative times in English.

const { IntlRelativeTimeFormat } = require('@formatjs/intl-relativetimeformat');
const rtf = new IntlRelativeTimeFormat('en', { numeric: 'auto' });
console.log(rtf.format(-1, 'day')); // Output: 'yesterday'
console.log(rtf.format(2, 'week')); // Output: 'in 2 weeks'

Customizing Numeric Display

This feature allows you to customize how numeric values are displayed. By setting the 'numeric' option to 'always', you can ensure that the output always includes the numeric value, even for common time frames like 'yesterday' or 'tomorrow'.

const { IntlRelativeTimeFormat } = require('@formatjs/intl-relativetimeformat');
const rtf = new IntlRelativeTimeFormat('en', { numeric: 'always' });
console.log(rtf.format(-1, 'day')); // Output: '1 day ago'
console.log(rtf.format(2, 'week')); // Output: 'in 2 weeks'

Localization Support

This feature demonstrates the library's support for multiple languages. The example shows how to format relative time strings in French.

const { IntlRelativeTimeFormat } = require('@formatjs/intl-relativetimeformat');
const rtf = new IntlRelativeTimeFormat('fr', { numeric: 'auto' });
console.log(rtf.format(-1, 'day')); // Output: 'hier'
console.log(rtf.format(2, 'week')); // Output: 'dans 2 semaines'

Other packages similar to @formatjs/intl-relativetimeformat

date-fns

date-fns is a modern JavaScript date utility library that provides a variety of functions for manipulating and formatting dates. It includes a function called formatDistance, which can be used to format relative time strings. Compared to @formatjs/intl-relativetimeformat, date-fns offers a broader range of date manipulation utilities but may require more configuration for internationalization.

moment

Moment.js is a widely-used JavaScript library for parsing, validating, manipulating, and formatting dates. It includes a fromNow method that can be used to format relative time strings. While Moment.js is feature-rich and easy to use, it is larger in size compared to @formatjs/intl-relativetimeformat and has been deprecated in favor of more modern alternatives.

luxon

Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It provides a method called toRelative, which can be used to format relative time strings. Luxon is a more modern and lightweight alternative to Moment.js, with better support for internationalization and time zones.

README

Intl RelativeTimeFormat

A spec-compliant polyfill/ponyfill for Intl.RelativeTimeFormat fully tested by the official ECMAScript Conformance test suite

Installation

npm install @formatjs/intl-relativetimeformat

Requirements

This package requires the following capabilities:

1. Intl.PluralRules
2. Object.is

NOTE: formatToParts only works on Node 10+ due to lack of Intl.NumberFormat.prototype.formatToParts natively

Usage

To use the polyfill, just import it to make sure that a fully functional Intl.RelativeTimeFormat is available in your environment:

import '@formatjs/intl-relativetimeformat/polyfill'

If Intl.RelativeTimeFormat already exists, the polyfill will not be loaded.

To use this as a ponyfill:

import IntlRelativeTimeFormat from '@formatjs/intl-relativetimeformat'

By default, this library comes with en data. To load additional locale, you can include them on demand:

import '@formatjs/intl-relativetimeformat/polyfill';
import '@formatjs/intl-relativetimeformat/dist/locale-data/de'; // Add locale data for de

If you want to polyfill all locales (e.g for Node):

import '@formatjs/intl-relativetimeformat/polyfill-locales'

Language Aliases

Language aliases are useful when we have to resolve deprecated locale (e.g zh-CN is technically zh-Hans-CN). Without aliases we would resolve zh-CN to zh which is less accurate. In order to include lang aliases, you can do:

import '@formatjs/intl-relativetimeformat/polyfill';
import '@formatjs/intl-relativetimeformat/dist/include-aliases'; // Add language aliases

Tests

This library is fully test262-compliant.

License

This software is free to use under the Yahoo! Inc. BSD license. See the [LICENSE file][license] for license text and copyright information.